Skip to main content

Access Control

ApertureDB authenticates database users and combines the permissions of their assigned roles. Database accounts are separate from ApertureDB Cloud logins. Changes to users, roles, sessions, and remote credentials succeed or roll back with the other database changes in the same query.

Connect to a database​

A fresh database creates the admin user and an admin role with all permissions. Its initial password comes from master_key in Configuration File; a nonempty ADB_MASTER_KEY environment variable takes precedence. Changing this setting does not reset an existing user’s password.

Submit Authenticate with a username and password or an assigned personal token. It returns a session token for subsequent query messages and a refresh token for RefreshToken. Client SDKs manage these tokens automatically. Authenticate and RefreshToken must each be the only command in their request, even when the request already carries a valid session.

Usernames have at least four characters, contain no whitespace, and cannot begin with _. Names beginning with _ are reserved for internal service accounts; these authenticate with the configured master key and have administrator access. CreateUser and UpdateUser passwords require at least ten characters, including a letter, digit, and punctuation, with no whitespace or unsupported characters. Keep passwords and tokens out of source control.

Assign permissions​

Each role has a name and independent create, read, update, and delete permissions in three categories:

  • objects: entities, connections, media, descriptors, and remote credentials.

  • indexes: property-index administration.

  • access_control: user and role administration.

An omitted permission is false. A user’s permissions are the union of all assigned roles; a role cannot revoke a permission granted by another role. Role names alone confer no permissions.

An administrator can create a read-only role and its user in one transaction:

[
  {"CreateRole": {"name": "reader", "objects": {"read": true}}},
  {"CreateUser": {
    "username": "reader_user", "password": "<strong-password>",
    "roles": ["reader"]
  }}
]

Use a new client connection as that user. FindEntity is allowed; AddEntity is rejected. Inspect GetUserDetails and GetRoles when diagnosing unexpected access. A user may inspect their own details; inspecting another user requires access_control.read.

Permissions during a request​

Your session must be valid and have the required permissions when database commands begin. If it expires or is revoked while the request is waiting or loading media, the commands are rejected without committing database changes.

Once commands begin, the query uses the same permissions throughout. Changing a user or role in that query does not change what its later commands are allowed to do. For example, a query cannot grant itself permission to run its next command. Affected users must authenticate again to use changed permissions.

Manage personal tokens​

GenerateToken returns a new adbp_ personal token. Generation alone grants no access. Assign the complete value with UpdateUser’s add_tokens array, then use it in Authenticate in place of a password. Retain the complete value securely: inspection returns only its tag, the first 13 characters.

Remove a token with UpdateUser’s remove_tokens array, supplying its tag or complete value. An added token replaces any existing token with the same tag. User updates revoke all that user’s existing session and refresh tokens, including sessions originally authenticated using a different personal token.

Manage your account in the Web UI​

Use the user menu to change your password or manage personal tokens. After a successful change, the Web UI confirms that it was saved and asks you to sign in again. When adding personal tokens, copy the complete values from the confirmation before continuing; they cannot be retrieved later.

Editing your own account or one of its roles from Access control also requires sign-in again after the change succeeds. Changes to other users and roles do not end your session unless they affect your account.

Open the Web UI over HTTPS, or use localhost for a local deployment. Tabs share your sign-in; signing out in one tab signs out the others.

Understand session lifetime​

Session tokens begin with adbs_ and refresh tokens with adbr_. By default, they remain valid for 10 hours and 100 hours respectively. Refresh replaces both tokens together and starts their lifetimes again. Expired session tokens can still be refreshed while their corresponding refresh token is valid.

Each user may retain max_sessions_per_user sessions, default 1024. At the limit, a successful sign-in revokes the oldest session and its refresh token to make room. Sessions with expired refresh tokens no longer count toward the limit. Refresh replaces a session and makes it the newest without consuming an extra slot. Equally old sessions may be revoked in either order. Lowering the limit takes effect on the user’s next successful sign-in or refresh.

Changing or removing a user revokes all their sessions and refresh tokens. Changing or removing a role does the same for users assigned that role, including when the change grants more permissions. Affected users must authenticate again. In a cluster, other replicas may take a short time to reflect these changes.

See Configuration File for session lifetime and capacity settings.

Read audit records​

Enable enable_audit_logs in Configuration File to record authentication, authorization, and security changes. Query authorization records report whether the session and permissions were accepted. A successful authorization record does not mean the query committed; a later command can still fail.

Security-change events report whether a user, role, or credential change was saved. Rolled-back changes produce failure events. A success event means the change was saved, even if fetching media or returning the response later fails. Requesting another page of a batch does not repeat its changes or produce another success event for them.

Requests that fail before the access check, such as malformed requests or invalid media, do not produce a query authorization record. Security-change records identify the requesting user when their session can be identified, including when access is denied or a later step fails. Invalid sessions cannot be attributed to a user.

Transactions and upgrades​

User, role, and credential commands may be combined with graph commands. If execution fails, their changes roll back together. A failure while retrieving media or delivering the response can occur after commit; see Transactions and references before retrying writes.

Supported upgrades preserve existing users, roles, personal tokens, and remote credentials. Sign in again afterward: existing sessions and refresh tokens are not retained. Manage users, roles, and credentials through the API after the upgrade; editing the old access-control files no longer changes database access. Database backups include users, roles, and credentials. See Remote credentials for changes to credential commands during upgrades.